package org.apache.flink.runtime.resourceprovider;

import org.apache.flink.api.common.ConsumerID;
import org.apache.flink.runtime.resourceconsumer.RCRPRegistrationRejection;
import org.apache.flink.runtime.resourceconsumer.RCRPRegistrationSuccess;
import org.apache.flink.runtime.resourceconsumer.ResourceConsumerGateway;
import org.apache.flink.runtime.resourceconsumer.ConsumingMasterId;

/**
 * Listener for the {@link ConsumerLeaderService}. The listener is notified whenever a resource consumer gained
 * leadership for a registered job and the service could establish a connection to it. Furthermore,
 * the listener is notified when a job manager loses leadership for a job. In case of an error, the
 * {@link #handleError(Throwable)}} is called.
 */
public interface ConsumerLeaderListener {

    /**
     * Callback if a job manager has gained leadership for the job identified by the job id and a
     * connection could be established to this job manager.
     *
     * @param consumerId identifying the consumer for which the job manager has gained leadership
     * @param resourceConsumerGateway to the job leader
     * @param registrationMessage containing further registration information
     */
    void resourceConsumerGainedLeadership(
            ConsumerID consumerId,
            ResourceConsumerGateway resourceConsumerGateway,
            RCRPRegistrationSuccess registrationMessage);

    /**
     * Callback if the job leader for the job with the given job id lost its leadership.
     *
     * @param jobId identifying the job whose leader has lost leadership
     * @param jobMasterId old JobMasterId
     */
    void resourceConsumerLostLeadership(ConsumerID jobId, ConsumingMasterId jobMasterId);

    /**
     * Callback for errors which might occur in the {@link ConsumerLeaderService}.
     *
     * @param throwable cause
     */
    void handleError(Throwable throwable);

    /**
     * Callback if a job manager rejected the connection attempts of a task manager.
     *
     * @param jobId jobId identifying the job to connect to
     * @param targetAddress targetAddress of the responsible job manager
     * @param rejection rejection containing more information about the rejection
     */
    void consumerManagerRejectedRegistration(
            ConsumerID jobId, String targetAddress, RCRPRegistrationRejection rejection);
}
